package com.jade.bss.admin.role;

import java.security.Principal;
import java.util.List;

import com.jade.bss.admin.AdminException;
import com.jade.framework.base.criterion.Criteria;
import com.jade.framework.base.util.PagingList;

/**
 * The <code>RoleManager</code> is used for two purposes:
 * <p/>
 * <li> to provide the function of role management, including adding, modifing, removing and getting and son on.<p>
 * <li> to manage the relation between principal and role.</ul>
 *
 * @author sky
 * @version 1.0 13-4-18 上午9:35
 */
public interface RoleManager
{
    /**
     * Adds a new role. It's neccesary to check the role's name confliction.
     *
     * @param role the role to be added.
     * @return the ID of new role.
     * @throws AdminException if there is an existed role that has the same name as
     *                        the role to be added or some reasons that cause the operation can't be completed,
     *                        such as database error.
     */
    public int addRole(RoleEntry role)   throws AdminException;

    /**
     * Removes an existed role with the specified ID..
     *
     * @param id the ID of role to be removed
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public void removeRole(int id)
            throws AdminException;

    /**
     * Removes an array of roles.
     *
     * @param ids the array of role id
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public void removeRoles(int[] ids)
            throws AdminException;

    /**
     * Checks if the role with the specified name is existed.
     *
     * @param roleName the name of role
     * @return true if the role is existed, otherwise return false.
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public boolean roleExists(String roleName)
            throws AdminException;

    /**
     * Modifies the role information. It's neccesary to check if there is another role that has the same name as
     * the new name of this role.
     *
     * @param role the role with the new information
     * @throws AdminException if there is an existed role that has the same name as
     *                        the role to be added or some reasons that cause the operation can't be completed,
     *                        such as database error.
     */
    public void updateRole(RoleEntry role)
            throws AdminException;

    /**
     * Returns the role with the specified name. If any role can't be found, return null.
     *
     * @param name the role's name
     * @return the role with the specified name.
     */
    public RoleEntry getRole(String name);

    /**
     * Returns the role with the specified ID. If any role can't be found, return null.
     *
     * @param id the role's ID
     * @return the role with the specified ID.
     */
    public RoleEntry getRole(int id);

    /**
     * Returns the list of all roles.
     *
     * @return the list of all roles.
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public List<RoleEntry> listRole()
            throws AdminException;

    /**
     * Returns the list of all roles by type.
     *
     * @param type role type
     * @return the list of all roles.
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public List<RoleEntry> listRole(String type)
            throws AdminException;

    /**
     * Search the list of roles.
     *
     * @param criteria query's criteria
     * @return query's result
     */
    public PagingList<RoleEntry> queryRole(Criteria criteria);

    /**
     * Modifies the role's status.
     *
     * @param id     the role's ID.
     * @param status the new status of the role.
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public void updateStatus(int id, int status)
            throws AdminException;

//    /**
    //     * Returns the list of the roles that the given principal has.
    //     *
    //     * @param principal the princal entity.
    //     * @return the list of the roles
    //     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
    //     */
    //    public List<RoleEntry> listRole(Principal principal)
    //            throws AdminException;
    //
    //    /**
    //     * get principal entity list by role.
    //     *
    //     * @param roleId roleId
    //     * @return principal entity list
    //     */
    //    public List<Principal> listPrincipal(int roleId);
    //
    //    /**
    //     * Adds the given role into the list of the roles that belongs to the given principal.
    //     * It menas that the principal has the all permissions that the role has.
    //     *
    //     * @param principal the principal entity
    //     * @param roleId    the role's ID
    //     * @throws AdminException if the role is not existed or some reasons that cause the operation can't be
    //     *                        completed, such as database error.
    //     */
    //    public void addRoleToPrincipal(Principal principal, int roleId)
    //            throws AdminException;
    //
    //    /**
    //     * Adds an array of roles into the list of the roles that belongs to the given principal.
    //     * It menas that the principal has the all permissions that these roles have.
    //     *
    //     * @param principal the principal entity
    //     * @param roleIds   the array of IDs.
    //     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
    //     */
    //    public void addRoleToPrincipal(Principal principal, int[] roleIds)
    //            throws AdminException;
    //
    //    /**
    //     * Set the principal's role..
    //     * It menas that the principal has the all permissions that the role has.
    //     *
    //     * @param principal the principal entity
    //     * @param roleIds   the role's ID
    //     * @throws AdminException if the role is not existed or some reasons that cause the operation can't be
    //     *                        completed, such as database error.
    //     */
    //    public void setRoleToPrincipal(Principal principal, int[] roleIds)
    //            throws AdminException;
    //
    //    /**
    //     * Removes the given role from the list of the roles that belongs to the given principal.
    //     *
    //     * @param principal the principal entity.
    //     * @param roleId    the role's ID
    //     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
    //     */
    //    public void removeRoleFromPrincipal(Principal principal, int roleId)
    //            throws AdminException;
    //
    //    /**
    //     * Removes an array of roles from the list of the roles that belongs to the given principal.
    //     *
    //     * @param principal principal entity.
    //     * @param roleIds   the array of IDs.
    //     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
    //     */
    //    public void removeRoleFromPrincipal(Principal principal, int[] roleIds)
    //            throws AdminException;
    //
    //    /**
    //     * Removes all roles that the given principal owns.
    //     *
    //     * @param principal the principal entity
    //     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
    //     */
    //    public void removeRoleFromPrincipal(Principal principal)
    //            throws AdminException;
    //
    //    /**
    //     * Removes all principals that the given role.
    //     *
    //     * @param roleId the role's id
    //     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
    //     */
    //    public void removePrincipalFromRole(int roleId)
    //            throws AdminException;
}
